feat(auth): add JWT verification and API Gateway authorization - #8469

Applications that need a custom JWT verifier currently assemble signing-key refresh, token-profile validation, and Lambda authorization behavior themselves. This adds an optional Auth utility with a shared verifier for direct use, Event Handler middleware, and API Gateway authorizers.

This PR covers inbound JWT verification. OAuth client credentials, its documentation, tests, and outbound example have been removed for a separate follow-up; that implementation is preserved on bfreiberg:follow-up/oauth-client-8466.

Issue number: #8466 — inbound JWT portion of the RFC.

Summary

Changes

• Verify asymmetric signatures, exact issuer, resource audience, and required expiration. Add claim-presence requirements and exact expected_claims / expected_headers values to enforce provider-specific token purpose after baseline verification.
• Support static JWKS, OIDC discovery, coordinated refresh, maximum key age, unknown-key cooldown, and failure backoff. Include resource-bound Cognito access tokens and explicitly configured issuer groups.
• Protect Event Handler routes and produce REST/HTTP API authorizer responses. Keep scope checks, exception-safe claims cleanup, opt-in scalar context, and IAM policies restricted to the current request.
• Expose eight fixed AuthFailureReason string-enum values and retryability. Middleware callbacks receive them through AuthErrorContext; authorizers have an observation callback for rejected tokens and unavailable keys. Default responses remain generic, and the utility performs no automatic logging.
• Keep construction free of network I/O. Document the first-invocation latency versus cold-start failure tradeoff of explicit prefetch, and the different outage responses from middleware and API Gateway authorizers.
• Retain the declared urllib3 dependency in the Powertools Layer and end-to-end Layer builder. Document cryptography's architecture requirements.
• Move SAM infrastructure to examples/auth/templates/sam.yaml and build authorizers with the Auth extra separately from base-only backend artifacts. Disable authorizer-result caching in both Gateway examples.
• Include functional/TLS tests, API documentation, a testing helper, and an MCP SDK adapter that records sanitized JWKS availability failures.

User experience

from aws_lambda_powertools.utilities.auth import JWTVerifier

verifier = JWTVerifier(
    issuer="https://idp.example.com/",
    audience="https://orders.example.com",
    algorithms=["RS256"],
    required_claims=["sub"],
    expected_claims={"token_use": "access"},  # Adapt to the provider's profile.
)

@app.get("/orders", middlewares=[verifier.require(scopes=["orders:read"])])
def orders():
    return {"subject": app.context["claims"]["sub"]}

Applications can also call verify() directly or return authorize() from a Lambda authorizer. Error callbacks let the Lambda owner record fixed reasons and retryability without logging credentials. Invalid credentials still deny access; unavailable JWKS still fails an authorizer invocation even when a callback is configured.

Validation

The Layer matrix used urllib3 2.8.0 from the Layer with runtime boto3/botocore 1.42.97. Checks confirmed dependency constraints, module locations, a real SDK HTTPS request, remote discovery/JWKS verification, invalid-token rejection, and authorizer error visibility. The SAM checks used separate authorizer/backend artifacts on Python 3.12 x86_64; both APIs returned HTTP 500 during the controlled JWKS outage. Test infrastructure and signing material were removed afterward.

Functional tests use real signatures and in-memory providers; TLS tests use a loopback server with both closing and persistent connections. Deployment checks use a controlled HTTPS provider. They complement the repository tests and do not claim live Cognito/Keycloak interoperability coverage. Coverage thresholds and exclusions are unchanged.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.